上一篇解釋了範本階層在 Block Theme 幾乎原封不動，只是換了副檔名，這一篇要解釋一個更根本的問題：一個資料夾裡放的幾個 .html 檔 WordPress 憑什麼認得它是「Block Theme」而不是壞掉的傳統主題？答案就是theme.json，少了它，那些 templates/single.html 一個都不會生效。

在傳統佈景主題裡，決定主題「長相與行為」的責任散在好幾個地方：functions.php 註冊功能、style.css 定義樣式、還有一堆 add_theme_support() 呼叫，Block Theme 把這些整合到同一個檔案。理解 theme.json 最快的方式，就是把它想成「用宣告式設定，取代原本散落各處的 PHP 呼叫」。

先看它取代了什麼

傳統主題如果要開放編輯器的顏色選項、限制內容寬度、啟用特色圖片，你得在 functions.php 這樣寫：

add_theme_support( 'editor-color-palette', array(
	array( 'name' => '主色', 'slug' => 'primary', 'color' => '#0073aa' ),
) );
add_theme_support( 'post-thumbnails' );

同樣的事，在 Block Theme 裡改成一段 JSON：

{
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{ "name": "主色", "slug": "primary", "color": "#0073aa" }
			]
		},
		"layout": { "contentSize": "840px", "wideSize": "1100px" }
	}
}

差別不只是換個語法，add_theme_support() 是命令式的，你告訴 WordPress「去做這件事」。theme.json 是宣告式的，你描述「我要的結果長這樣」，剩下的交給 WordPress。

這個轉變帶來一個很實際的好處：同一份設定，前台輸出的 CSS、後台編輯器看到的選項、以及區塊工具列裡的控制項，全部在同一個檔案搞定，不會再出現「後台選得到、前台卻沒套上」的問題。

兩個主要區塊：settings 與 styles

theme.json 的內容九成落在兩個頂層鍵。

settings 決定「使用者能調什麼」。你在這裡開放的顏色、字級、間距，會變成編輯器裡實際可以點選的選項，像是上面的範例。沒開放的，編輯器就不會出現。這其實是一種設計約束，把品牌規範直接寫進工具，而不是寫在一份沒人看的 PDF 裡。

styles 決定「預設長什麼樣」。網站整體的背景色、內文字型、連結顏色、標題大小，都在這裡給預設值：

{
	"styles": {
		"color": { "background": "#ffffff", "text": "#1a1a1a" },
		"typography": { "fontSize": "18px", "lineHeight": "1.7" },
		"elements": {
			"link": { "color": { "text": "var(--wp--preset--color--primary)" } }
		}
	}
}

拿傳統主題類比：settings 像是你在 functions.php 裡註冊的那些「允許使用者調整的範圍」，styles 則像 style.css 裡寫死的預設樣式。以前這兩件事分別住在 PHP 和 CSS 兩個世界，現在併到同一份結構化設定裡。

為什麼這對 AI 開發特別友善

這點我在實際用 Claude Code 開發主題時感受最深。傳統主題的樣式邏輯藏在 CSS 選擇器的層層覆蓋、!important、還有跨檔案的繼承關係裡，AI 要改一個顏色，得先讀懂整條 cascade 才敢動手，改完還不確定會不會波及別處。

theme.json 是一份結構化、有 schema、單一來源的設定檔。要改主色，就是改 settings.color.palette 裡那一個值；要調內容寬度，就是改 layout.contentSize。

AI 不需要理解 CSS 的覆蓋順序，只要能讀懂 JSON，而讀 JSON 正是語言模型最擅長的事。第三部我們實際用 AI scaffold 主題時，你會看到 theme.json 幾乎是 AI 一次就能改對的檔案，這是宣告式設計帶來的好處。

一張表對照傳統主題

Block Theme 全部集中在同一個檔案，這就是它最核心的設計哲學：把分散的樣式決策，整合成一份宣告式的單一來源。

一個常見的誤會

很多人第一次看到 theme.json 會以為那是不是所有 CSS 都得寫進 JSON？要澄清的是 theme.json 管的是設計系統層級的東西，色票、字級、間距、版面寬度這些「設計元素」（design token）。真正細節、一次性的樣式，你還是可以用傳統的 CSS 檔補上。theme.json 負責定調，CSS 負責收尾，兩者並存。

搞懂 theme.json，等於拿到了 Block Theme 的鑰匙，但光有鑰匙還不夠，明天我們要打開的是那扇更大的門：全站編輯（Full Site Editing），當使用者可以在後台直接拖拉整個網站的頁首、頁尾、模板，開發者和維運者的分工，會被徹底改寫。

文章目錄：https://oberonlai.blog/category/2026-ithome/